% Created 2009-09-14 Mo 21:49
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{hyperref}
\usepackage{listings}
\renewcommand{\familydefault}{\sfdefault}


\title{SecondLife CICP Adapter - User manual}
\date{14 September 2009}

\begin{document}

\maketitle

\setcounter{tocdepth}{3}
\tableofcontents
\vspace*{1cm}

\section{SecondLife CICP Adapter - User manual}
\label{sec-1}


This page explains how to use the version (1.2) of the SecondLife
CICP Adapter. Read the section Quick Start to get started immediately.


\subsection{Quick Start}
\label{sec-1.1}


Follow these instructions for the quickest way to get a graph inside
SecondLife.

\begin{enumerate}
\item Rez slcicp somewhere.
\item Wait until it loaded configuration.
\item Click it and choose ``Rez prims'' from the menu.
\item Wait until it finished rezzing prims.
\item Click it and choose ``Gateway'' from the menu.
\item A sphere appears above the slcicp prim.
\item Move it where your graph should be and click it to start.
\item Click the new sphere that appeared and select the gateway.
\item Wait until the graph cube comes up and click it.
\item Select the graph you want.
\item Enjoy!
\end{enumerate}
\subsection{Configuration}
\label{sec-1.2}


Before you start with graphing, you may want to configure the SecondLife
Adapter. The configuration is stored in the file \textbf{config} inside the slcicp
prim. Read the section \textbf{How to open configuration} to get to know how you
can change the config file.

\subsubsection{How to open configuration}
\label{sec-1.2.1}


 To change the value of a config variable, you have to edit the notecard
\textbf{config} in your slcicp prim.

To be able to do this, you have to rez the slcicp prim and do a right-click
on it and select ``Edit''. An additional window will pop up (mostly on the
right side) giving you some general information about the prim. Change to
the tab ``Contents'', where you should have listed the contents of the slcicp
prim.

Double-click the notecard \textbf{config} (inside the slcicp prim contents) and
wait for it to be loaded. Don't forget to save the file after you made
changes to it.

\subsubsection{The config file syntax}
\label{sec-1.2.2}


Every line in the config file can set one variable. Empty lines will be
ignored as well as any whitespaces. If \#\# appears, the rest of the line
will be ignored (use it for commentary).

The basic syntax of a line to set a variable is like so

\begin{lstlisting}
<variable_name> <variable_value>
\end{lstlisting}

This sets the variable <variable\_name> to the value <variable\_value>. Any
preceeding and following whitespace will be ignored as well as any
whitespace between these two. The following example would lead to the same
result:

\begin{lstlisting}
    <variable_name>   <variable_value>       ## yeeha, a comment!
\end{lstlisting}

The config file is read from top to bottom, which means, that the latest
variable setting will be taken. For example if you define the same variable
twice in the \textbf{config} file, only the last definition will be taken.

\subsubsection{The config variables}
\label{sec-1.2.3}

There are some variables recommended to change if you want to start
graphing. Each variable is commented in the config files and provides small
information about what it's doing. Here are some further explanations you
might want to read:


\begin{center}
\begin{tabular}{|l|l|l|p{5cm}|}
 *  &  Variable name                         &  values                 &  description                                                                              \\
\hline
 *  &  cicp\_url                 &  string (url)           &  the valid url of your hub on the your server                                             \\
    &  ssl                                   &  bool (true/false/1/0)  &  indicates use of ssl while cicp communication                                            \\
 *  &  sheep\_prims              &  integer                &  how many cicp prims should be rezzed (check for the region limitations)                  \\
    &  prim\_channel\_{}offset   &  integer                &  sets a minimum offset from 0 for the channels of cicp prim communication                 \\
    &  graph\_channel\_{}offset  &  integer                &  offset from 0 for channel used by entire graphs to communicate                           \\
    &  cicp\_hub\_{}name         &  string                 &  title or name of the cicp hub; this aesthetic variable does not influence functionality  \\
\end{tabular}
\end{center}



Rows marked with * are important for basic
functionality. Please have a closer look to these variables and set them
accordingly.

\subsection{CICP Prim Interaction}
\label{sec-1.3}


The cicp prims rezzed by the slcicp prim are able to fulfill the various
needs of the CICP protocol.  The CICP hub can send instructions to the cicp
prims to change their shape and most of the other properties the prims
have. Additionally, every cicp prim is able to indicate highlighting, show
titles and provide menus.

When the cicp prims are in use, which means the CICP hub has modified them,
they react on touches to toggle highlighting and title and display menus as
listed in the following table:


\begin{center}
\begin{tabular}{rl}
 Touch \#  &  What happens?                                         \\
\hline
        1  &  prim gets highlighted and toggles title display       \\
        2  &  prim displays a menu                                  \\
        3  &  prim turns highlighting off and resets touch counter  \\
\end{tabular}
\end{center}



The number in the column \textbf{Touch \#} indicates the number of touches/clicks
on the prim to act like described in the column on the right.

\subsection{The slcicp Menu}
\label{sec-1.4}

When clicking the slcicp prim, it shows up a menu with a few different
actions:

\begin{itemize}
\item \textbf{Gateway}
    Rez a new gateway prim (green sphere)
\item \textbf{Rez prims}
    Rez cicp prims
\item \textbf{Delete}
    Delete all cicp prims
\item \textbf{Reset}
    Reset all cicp prims
\item \textbf{Reload conf}
    Reload the configuration file
\end{itemize}
The actions \textbf{Delete} and \textbf{Reset} work on all cicp prims in the region, so
if you want to clean up the space or run into problems, just select
``Reset'', which will reset \textbf{all} cicp prims (even they're in a graph) in the
region and move them to the slcicp prim.

If you have made changes to the configuration file, \textbf{Reload conf} forces
the slcicp to reload it and updates it in every cicp prim. Be careful
when changing the cicp\_url, as the cicp prims will continue to use the new
url you set in the configuration file. Perform a ``Reset'' first if you want
to be on the secure side.

Be aware, that \textbf{Rez prims} will rez the amount of prims defined by sheep\_prims in the config file in \textbf{every case} without checking if there are already rezzed prims. Perform \textbf{Delete} first to make sure you don't double the cicp prims by accident.

Note: It is \textbf{not} a good idea to perform \textbf{Rez prims} several times with the
goal to have more cicp prims. The cicp prims are numbered and this will
create several conflicts. If you want to have more cicp prims, raise the
number of sheep\_prims in the config and \textbf{Delete} the existing ones, \textbf{Reload conf} and \textbf{Rez prims}.

\subsection{The Gateway Prim}
\label{sec-1.5}

The gateway prim is your start point to create graphs. A touch on it and
the the CICP communication starts. After this touch, you will have not
chance to change the position where the graph will be created.

So please move the gateway prim first to the position where you want the
graph's origin to be, and then touch it.

Tip: Drag the gateway prim \textbf{cicp\_start} directly from inventory onto the
ground where you want the graph to be - touch it and it will create the
graph on the position where you placed the prim.

\subsection{FAQ/Help guide}
\label{sec-1.6}


\subsubsection{Q: I'm getting the error "not enough cicp prims" or similar.}
\label{sec-1.6.1}


    A: The graph you want to create needs more cicp prims to be fully
    displayed. Delete the cicp prims and raise the number of total prims in
    the config (variable \textbf{sheep\_prims}), then perform \textbf{Reload conf} to load
    the changes and rez the prims again with \textbf{Rez prims}.

\subsubsection{Q: I messed it up! / My graphs going crazy! / Somethings wrong! / Basic help}
\label{sec-1.6.2}


    A: If something is going wrong or you think you lost control over your
    cicp prims, try resetting all prims with \textbf{Reset} in the slcicp menu. If
    that does not help, try the following:
\begin{enumerate}
\item Delete the prims with \textbf{Delete}
\item Do a reload of configuration with \textbf{Reload conf}
\item Re-rez the prims with \textbf{Rez prims}
\end{enumerate}
\subsubsection{Q: The slcicp prim says something about config variables which I don't understand.}
\label{sec-1.6.3}


    A: Read carefully what the prim is saying to you - there seems to be a
    conflict with your configuration. Try to follow the instructions and
    reload the config (\textbf{Reload conf}) when made the changes (don't forget
    to save the config file).

    Check our wiki on
    \href{http://wizardsguild.pbworks.com/SecondLife-CICP-Adapter-Feature-Plausibility-check-for-configuration-values}{http://wizardsguild.pbworks.com/SecondLife-CICP-Adapter-Feature-Plausibility-check-for-configuration-values}
    for more information.

\subsubsection{Q: I get the error "Config variable XY not found.".}
\label{sec-1.6.4}


    A: Compare your config file to the one you received with your
    slcicp. Make sure that every variable in the default config file is
    defined in your config file. If this is the fact, make sure you tried
    to reload the conf with \textbf{Reload conf}.

    If the error comes up again, report the error message into the issue
    tracker (\href{http://code.google.com/p/cicp/issues/list}{http://code.google.com/p/cicp/issues/list}) - seems you have 
    discovered a bug in the slcicp source.

\subsubsection{Q: I get the error "Could not rez cicp starter prim \ldots{} not in object's inventory.".}
\label{sec-1.6.5}


    A: The slcicp prim could not find the gateway prim in its
    inventory. Please make sure that if you created the slcicp prim from
    the repo sources, that you put the objects into the slcicp prim and
    named it correctly.
    
    If you purchased this version over XStreetSL, it may have
    broken. Please purchase another copy and try again.

\subsubsection{Q: I get the error "No configuration found \ldots{} using default config.".}
\label{sec-1.6.6}

    
    A: Make sure the slcicp prim contains the configuration file \textbf{config}
    and that it is named correctly.  See also FAQ above (''Could not rez
    cicp starter prim\ldots{}'').

\end{document}
